/**
 * Vue Router 详细讲解
 * 
 * Vue Router 是 Vue.js 官方的路由管理器，它允许我们构建单页面应用（SPA）
 * 主要功能包括：
 * 1. 嵌套路由映射
 * 2. 动态路由选择
 * 3. 模块化、基于组件的路由配置
 * 4. 路由参数、查询、通配符
 * 5. 视图过渡效果
 * 6. 细粒度的导航控制
 * 7. HTML5 历史模式或 hash 模式
 * 8. 自动激活 CSS 类的链接
 * 9. 路由懒加载
 */

// 从 vue-router 导入创建路由器和历史模式的函数
import {createRouter, createWebHistory} from 'vue-router'

/**
 * createRouter: 创建路由实例的函数
 * createWebHistory: 创建 HTML5 历史模式的函数，使用真实 URL 路径
 * 其他历史模式选项:
 * - createWebHashHistory: 使用 URL hash 模式 (#)
 * - createMemoryHistory: 主要用于服务器端渲染
 */

// 创建路由
const router = createRouter({
    // 设置路由历史模式
    history: createWebHistory(), // 使用 HTML5 History API，URL 看起来更美观，没有 # 符号
    
    // 路由配置数组，每个对象代表一个路由
    routes: [
        {
            name: '主页', // 路由名称
            path: '/home', // 路由路径，访问 /home 时匹配此路由
            component: () => import('@/views/home/index.vue'), // 路由懒加载，按需加载组件
            // 其他可选配置:
            // name: 'home', // 路由名称，可用于命名路由导航
            // meta: { requiresAuth: true }, // 元信息，可用于权限控制等
            // props: true, // 将路由参数作为组件的 props
            // children: [], // 嵌套路由
            // beforeEnter: (to, from, next) => {} // 路由独享的守卫
        }, 
        {
            name: '关于', // 路由名称
            path: '/about',
            component: () => import('@/views/about/index.vue')
        }, 
        {
            name: '用户', // 路由名称
            path: '/user',
            component: () => import('@/views/user/index.vue')
            // 动态路由示例:
            // path: '/user/:id', // :id 是动态参数
            // 访问方式: this.$route.params.id 或在 setup 中使用 useRoute().params.id
        }, 
        {
            name: '新闻', // 路由名称
            path: '/news',
            component: () => import('@/views/news/index.vue'),
            children: [
                // 路由规则 ，通过占位实现
                // {
                //     name: '新闻详情', // 路由名称
                //     path: 'detail/:title/:content/:date?', // 路由名称 ?表示可选参数，占位表示路由是通过params传递的
                //     component: () => import('@/views/news/detail/index.vue') 
                // }
                // 路由规则 ，通过props传递
                {
                    name: '新闻详情', // 路由名称
                    path: 'detail', // 路由名称 ?表示可选参数，占位表示路由是通过params传递的
                    component: () => import('@/views/news/detail/index.vue'),
                    // props: true //将路由收到的所有params参数作为props传递给组件
                    // props: true // 将路由参数作为组件的 props
                    // 将路由参数作为props传递给组件，可以使用函数返回一个对象
                    props(route) { return route.query } 
                }   
            ]
        }, 
        // {
        //     path: '/',
        //     redirect: '/home' // 重定向路由
        // },
        {
            name: 'props1',
            path: '/props1',
            component: () => import('@/views/props/father.vue')
        },
        {
            name: 'custom-event-view',
            path: '/custom-event-view',
            component: () => import('@/views/custom-event/father.vue'), 
        },
        {
            name: 'mitt-view',
            path: '/mitt-view',
            component: () => import('@/views/mitt/father.vue'), 
        },
        {
            name: 'v-model-view',
            path: '/v-model-view',
            component: () => import('@/views/v-model-view/father.vue'), 
        },
        {
            name: 'attrs-view',
            path: '/attrs-view',
            component: () => import('@/views/$attrs-view/father.vue'), 
        },
        {
            name: 'refs-view',
            path: '/refs-view',
            component: () => import('@/views/$refs-parent/father.vue'), 
        },
        {
            name: 'provide-inject-view',
            path: '/provide-inject-view',
            component: () => import('@/views/provide-inject-view/father.vue'), 
        },
        {
            name: 'pinia-view',
            path: '/pinia-view',
            component: () => import('@/views/pinia-view/father.vue'), 
        },
        {
            name: 'slot-view',
            path: '/slot-view',
            component: () => import('@/views/slot-view/father.vue'), 
        }
        /**
         * 其他常用路由配置示例:
         * 
         * 1. 重定向路由
         * {
         *   path: '/',
         *   redirect: '/home' // 或 { name: 'home' }
         * }
         * 
         * 2. 404 路由 (放在最后)
         * {
         *   path: '/:pathMatch(.*)*',
         *   component: () => import('@/views/NotFound.vue')
         * }
         * 
         * 3. 嵌套路由
         * {
         *   path: '/parent',
         *   component: Parent,
         *   children: [
         *     { path: 'child', component: Child } // 访问 /parent/child
         *   ]
         * }
         * 
         * 4. 命名视图 (一个路由显示多个组件)
         * {
         *   path: '/dashboard',
         *   components: {
         *     default: Dashboard,
         *     sidebar: Sidebar,
         *     header: Header
         *   }
         * }
         */
    ]
})

/**
 * 全局前置守卫 - 在路由跳转前触发
 * 常用于:
 * 1. 身份验证检查
 * 2. 权限控制
 * 3. 数据预加载
 * 
 * router.beforeEach((to, from, next) => {
 *   // to: 即将进入的路由对象
 *   // from: 当前导航正要离开的路由对象
 *   // next: 函数，必须调用以继续导航
 *   
 *   if (to.meta.requiresAuth && !isAuthenticated) {
 *     next('/login')
 *   } else {
 *     next() // 继续导航
 *   }
 * })
 */

/**
 * 全局解析守卫 - 在导航被确认前触发
 * router.beforeResolve((to, from, next) => {
 *   // 与 beforeEach 类似，但在所有组件内守卫和异步路由组件被解析后触发
 *   next()
 * })
 */

/**
 * 全局后置钩子 - 在路由跳转完成后触发
 * router.afterEach((to, from) => {
 *   // 不接受 next 函数，不能改变导航
 *   // 常用于分析、更改页面标题等
 *   document.title = to.meta.title || 'Default Title'
 * })
 */

/**
 * 路由懒加载
 * Vue Router 支持使用动态导入来实现组件的懒加载
 * 这意味着组件只会在被访问时才会被下载
 * 
 * 好处:
 * 1. 减小初始包体积
 * 2. 提高首屏加载速度
 * 3. 按需加载资源
 * 
 * 实现方式:
 * - 使用 import() 函数 (如本例所示)
 * - 可以使用 Webpack 的命名 chunk: import(/* webpackChunkName: "about"  './about.vue')
 */

/**
 * 在组件中使用路由
 * 
 * 1. 在模板中使用:
 *    <router-link to="/home">首页</router-link>
 *    <router-view></router-view>
 * 
 * 2. 在 Options API 中:
 *    this.$router.push('/home')
 *    this.$route.params.id
 * 
 * 3. 在 Composition API 中:
 *    import { useRouter, useRoute } from 'vue-router'
 *    
 *    const router = useRouter() // 获取路由器实例
 *    const route = useRoute()   // 获取当前路由对象
 *    
 *    router.push('/home')       // 导航到指定路由
 *    console.log(route.params.id) // 访问路由参数
 */

/**
 * 常用的路由导航方法:
 * 
 * 1. router.push() - 导航到新路由
 *    router.push('/home')
 *    router.push({ path: '/home' })
 *    router.push({ name: 'home', params: { id: 123 } })
 *    router.push({ path: '/search', query: { q: 'vue' } }) // /search?q=vue
 * 
 * 2. router.replace() - 替换当前路由 (不会添加新历史记录)
 *    router.replace('/home')
 * 
 * 3. router.go() - 在历史中前进或后退
 *    router.go(-1) // 后退一步
 *    router.go(1)  // 前进一步
 * 
 * 4. router.back() - 后退一步
 * 
 * 5. router.forward() - 前进一步
 */

// 导出路由
export default router
